package toman.orm;

/**
 * This annotation marks TO classes for recognizing them by a query engine, which interpret the query definition written
 * in a syntax of a query language, like SQL, JPQL or Hibernate query engines. The information carried by
 * this annotation provides the query language's fragments for establishing reading, writing and identifying the raw
 * data for building the annotated TO.
 */
@java.lang.annotation.Target({java.lang.annotation.ElementType.TYPE})
@java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.RUNTIME)
public @interface TO {
    /**
     * @return The query language fragment for selecting raw data for assembling the TO. Its purpose is to define
     * the source entity or enumerate the attributes that constitute the TO. In the first case the TO is initialized
     * from the entity object (bean). The fields or setters in the TO class reference are annotated with Prop
     * annotations pointing to an entity's property. In the case of the array each element appearing right
     * after the SELECT keyword must correspond to a field in the TO class. Each such a field must be annotated with
     * annotation @Index that binds the field to the corresponding element in the SELECT clause using its index in
     * the list. This expression is concatenated with the value in the id attribute when finding the TO for a given
     * unique (primary) key. It also used when querying the database for a list of TOs. In such a case this
     * expression is concatenated with the WHERE clause fragment provided by the client code (the second argument of
     * the createQuery method).
     */
    String read() default "";

    /**
     * @return The query language fragment fragment used for updating the database with the state in the TO.
     * Before updating this expression is concatenated with value in the id attribute. This query fragment may
     * contain QL named parameters. The values for these parameters are taken from properties of the TO used for
     * the update operation.
     */
    String write() default "";

    /**
     * @return Expression fragment allowing selecting exactly one raw data for assembling the TO or updating. This
     * QL fragment is concatenated with the expressions in the remaining attributes either to find a TO for a given ID
     * or to update the database with the TO's data.
     */
    String id() default "";
}
